|
|
WebsydianExpress calls the defined web services based on the service structure. These definitions make it possible for you to use several different pre-defined criteria to identify which service handler to call. These options will be sufficient for most cases, but in some cases you will need to define your own logic for selecting the service handler to call.
This document describes a fairly advanced use of the service structure.
Before proceeding with this example, it is important that you have at least a basic understanding of how web services are handled in WebsydianExpress. If you have not already done so, we recommend that you read:
This document will show how you can solve a relatively common way to identify the service handler to call for an XML-based service. The case is that several different request documents can target the same URL. Each document contains information about it's request type.
The basic structure of all the request documents is the same:
1. The top element of the document is named "ExampleDocument"
2. This contains a complex element named "Header", which contains a simple element: "RequestType", which identifies the service to call.
3. The "ExampleDocument" contains another complex element, which is the payload of the request document. The format of this payload can be different for each service.
Example:
The value specified for the "RequestType" field can be compared with the SOAPAction of a SOAP based service. It uniquely identifies a specific service that must receive the document as the response document. But unlike the SOAP-based services, WebsydianExpress does not have any functionality to handle this specific type of request documents. This document will show how you can create the necessary functionality to handle documents of this type.
Note that the functionality described in this document uses functions and modeling based on TransacXML.
You can only use this specific functionality if your local model has WSYAPIWS and its dependent models as library models.
This also means that this functionality is not available in the RPG variant.
Download a local model that shows an implementation of the Plex objects described below.
The Plex model is developed in Plex 6.0. If you are using a later Plex version, you will get a warning when you open the local model. Just accept this to access the model.
The model contains:
This is the function that is used to determine which service handler to call based on the RequestType of the request document.
This is an example xmlservicehandler that can process the example document. This is not really necessary for the example itself - but it does make it possible to generate and build a functioning case from the model.
This scopes the TransacXML model for the request document. This is use partly by MyCriteriaProgram to extract the value for RequestType and partly by ExampleHandler to read the payload of the request document.
This scopes the TransacXML model for the response document of the Greet service. This is used by ExampleHandler to create the response document.
The first thing to do is to create the program that WebsydianExpress will call to identify the service handler that ultimately must receive and handle the request document.
Selection programs are called dynamically by the WebsydianExpress service processor. Because of this, the program must have a specific interface. The program gets this interface by inheriting from the abstract function Abstract.SelectionProgram from the WSYAPI model. Note that you may not change the interface of the function.
The selection program is created by the following triples:
| Source Object | Verb | Target Object |
|---|---|---|
| MyCriteriaProgram | is a FNC | WSYAPI/Abstract.SelectionCriteriaProgram |
| MyCriteriaProgram | implement SYS | Yes |
| MyCriteriaProgram | impl name NME | MYSELECT |
The selection program has three different tasks:
MyCriteriaProgram will ultimately be called by a service processor. As this is an XML-based service, the most fitting service processor to choose is the XMLServiceProcessor.
When an XMLServiceProcessor loads the document in the XML parser, it saves the resulting references to memory. This information can be retrieved by calling the API: WSYAPIWS/XMLAPI._Parameters.GetXMLDoc, while specifying the value <APIFields.WSType.Input> for the input parameter.
This function returns the ObjectStoreReference and the ObjectDocument, which is the information that is necessary to access the document using TransacXML functions.
The easiest way to retrieve the RequestType value from the request document is to model the top part of the document in TransacXML. You do this by creating the following triples:
| Source Object | Verb | Target Object |
|---|---|---|
| ExampleDocument | is a ENT | WSYXML/XMLElement |
| ExampleDocument | includes ENT | Header |
| ExampleDocument.Header | is a ENT | WSYXML/XMLElement |
| ExampleDocument.Header.Fields | field FLD | RequestType |
| ExampleDocument.Header | has FLD | ExampleDocument.Header.Fields.RequestType |
| ExampleDocument.Header.Fields.RequestType | is a FLD | WSYXML/ElementField |
This provides you with functions that you can use to read the RequestType value.
This returns the unique identification of the Header element.
This returns the value of the RequestType simple element (in the example document above this would be "GREET").
All the service handlers that can be selected by the selection program will be scoped by one criterion node in the service structure. When each service handler is added to the criterion, the user is prompted for a criteria value. This is where he will specify the value for RequestType that will specify that the service handler being added is the one to be called.
The unique identification of the criterion node is transferred as input parameters to MyCriteriaProgram:
Using this information together with the RequestType value retrieved from the request document, the API: WSYAPI/APIServer.WebServices.FindOfferedService can be used to find the service handler to call. This function iterates over the service handlers scoped by the specified criterion node until it finds the one that has the same criterion value as the one that was retrieved from the request.
When calling the FindOfferedService API, specify the input parameters for MyCriteriaProgram for the ServiceURLSurrogate and CriteriaSequence parameters. Specify the retrieved output from the call to ExampleDocument.Header.SingleFetch for the CriteriaValue parameter.
This function returns information about the service handler that corresponds to the retrieved criterion.
MyCriteriaProgram must return the unique identification of the service handler as an output parameter. To do so, set the value of Output/Output<APIFields.ServiceHandlerSurrogate> to the ServiceHandlerSurrogate returned by the call to WSYAPI/APIServer.WebServices.FindOfferedService.
The last thing that is necessary is to define MyCriteriaProgram in the service structure, and to add the service handlers to the resulting criterion node.
This process has three steps:
1. Define an XMLServiceProcessor that will receive the requests and act as dispatcher for a specific URL
2. Add MyCriteriaProgram as a "Program" criterion to the service processor
3. Add the service handlers to the criterion node
In the service structure, select the top element of the service structure and press "Add". Select "XML Processor (WSSELX) for the Service processor - and enter values shown below - press "Enter" to create the service processor.
This creates a service processor node in the service structure.
Select this node and press "Add" to add MyCriteriaProgram as a selection criterion for this service processor.
Select "Program" for Criterion. This opens the "Program name" field. Specify "MYSELECT" as a value for this field. This is the implementation name of MyCriteriaProgram.
Press "Insert" to create the criterion node.
At this point, all requests that is targeted at the service URL of the site followed by "example" will be processed by the standard XMLServiceProcessor, which will call MyCriteriaProgram to identify which service the specific request document targets.
You can add any number of service handlers to the criterion node. The following just shows how to add one handler - the one that will be called when the RequestType is "GREET".
Select the criterion node and press "Add".
This leads to a page, where you can select an existing service handler. As the service handler to call for the greet request is not pre-defined, press "Insert" to create the service handler.
Specify the implementation name of the service handler function in the "Program" field. In the Plex model, you can find an example implementation of a service handler that can handle the service request - the implementation name of this is "MYHANDLER".
Press Insert to create the service handler.
This returns to the page, where you can select the service handler to add - the newly created service handler will be pre-selected.
Press "Select" to add the service handler.
This pops a window, where you must specify the criterion value for the service handler - in this case, specify "GREET" - as this is the RequestType value that corresponds to this service handler.
Press "Insert to add the service handler.
This adds the service handler to the criterion node, with the criteria value "GREET".
As mentioned, you can add any number of service handlers, each with a separate value for the RequestType value to the criterion node. As the service processor is a standard XMLServiceProcessor, you can even add more criteria nodes to the service processor node - but this is outside the scope of this document.
Background: Handling web service requests
Background: Understanding the service structure
Background: Service Processors
Background: Selection Criteria
TransacXML Background: Modeling XML documents
TransacXML Background: Reading XML documents
Online documentation - WebsydianExpress v3.5